Skip to content

feat(sdk): add CXX bindings over dash-sdk for C++ embedders - #4633

Draft
PastaPastaPasta wants to merge 1 commit into
feat/shared-dpns-dashpay-buildersfrom
feat/platform-sdk-cxx
Draft

feat(sdk): add CXX bindings over dash-sdk for C++ embedders#4633
PastaPastaPasta wants to merge 1 commit into
feat/shared-dpns-dashpay-buildersfrom
feat/platform-sdk-cxx

Conversation

@PastaPastaPasta

Copy link
Copy Markdown
Member

Issue being fixed or feature implemented

Stacked on #4632 (review from feat(sdk): add CXX bindings onward). Replaces #4620, and with it the reason for #4618's decoder crate on the Core side (see dashpay/dash#7512).

Dash Core's platform GUI needs Dash Platform from C++ with its own trust context and signing keys: quorum keys from its locally synced LLMQ store, evonode endpoints from its deterministic masternode list, signatures from its wallet, and no key or trust ever leaving the node. rs-sdk-ffi is a C ABI shaped for mobile wallets that fetch quorum keys from a trusted HTTP service and hold private keys in-process, so it does not fit. The previous approach (#4620) kept the SDK's networking out and had C++ own the DAPI transport, which required reconstructing document queries from wire bytes (#4618, #4619) to verify proofs against them.

The maintainers' direction was to use the SDK instead. This PR does that: dash-sdk owns query construction, transport (TLS to the evonodes), retries with address banning, proof verification and protocol-version tracking; Core supplies what only it knows. Queries go through the SDK's Fetch/FetchMany, so the SDK verifies against the rich query it built and no wire request is ever reconstructed from bytes.

Measured before choosing: the full SDK type-checks for x86_64/aarch64 Linux musl, x86_64-pc-windows-gnu, and riscv64gc-unknown-linux-gnu (in a container with a pinned protoc); a release-built C++ driver against live testnet verified identity, nonce, DPNS resolve (registered and proven absent), names-of-identity, prefix search, profile, contact requests, contested vote state and a rejected broadcast in 0.3 to 2 s each, with bit-flipped quorum keys failing at the BLS check; a statically linked x86_64-unknown-linux-musl build of the same driver ran under emulation with identical results. macOS needs Security + CoreFoundation (rustls reads the system trust store); Windows needs ws2_32 bcrypt crypt32 userenv ntdll. Dependency graph: 337 crates vs 281 for the transport-free crate.

What was done?

packages/rs-platform-cxx, a thin cxx bridge over dash-sdk:

  • client.rs: one Sdk instance, the tokio runtime that drives it, and the embedder's freshness policy. The embedder pushes endpoints, Platform quorum keys and its best ChainLock height; Client::fetch runs an SDK operation and then applies the chain-id check and the ChainLock staleness floor (signed core-chain-locked height must not trail the embedder's ChainLock by more than 288 blocks) on top of the SDK's signed-time window and monotonic Platform height. The verified-height watermark survives an SDK rebuild on endpoint changes. shutdown cancels in-flight work and releases the runtime.
  • queries.rs: identities (by id, by unique public key hash), identity and identity-contract nonces, DPNS resolve/search/names-of-identity, DashPay profile and contact requests, contested-name vote state, and broadcast. Broadcast runs the raw DAPI request with address banning off (a node rejecting our transition is not a failing node) and reports the decoded consensus error code and message.
  • provider.rs: a ContextProvider over the pushed quorum keys and the pinned DPNS/DashPay contracts; a proof naming any quorum type other than the network's Platform type is refused before its key is looked up.
  • st.rs: state-transition construction with dpp's Signer over a C++ digest callback (WalletSigner, include/dash/platform/signer.h); document assembly is dash-platform-queries' pure builders from feat(sdk)!: pure DPNS and DashPay document builders shared with embedders #4632. Structure validation runs before serialization, as dash-sdk does before broadcast.
  • Every fallible bridge entry point runs under catch_unwind, so a panic anywhere in the SDK surfaces as rust::Error; build.rs refuses panic = "abort". build.rs stages include/dash/platform/{ffi.h,signer.h} and include/rust/cxx.h under target/<profile>/; consumers vendor from the workspace root (build: make the workspace lockfile vendorable with --locked #4631) and install that tree plus the static archive.
  • CI: the crate is checked, its tests run under nextest, and scripts/cxx-smoke.sh links and runs tests/cxx_smoke.cc from C++.

How Has This Been Tested?

  • tests/queries.rs replays drive-proof-verifier's proof-vector corpus through dash-sdk's mock transport: only the socket is mocked, the SDK's FromProof path runs the GroveDB replay and the BLS quorum check against the key the test pushed through the client. Covers unknown quorum key, wrong quorum type, tampered signature, a validly signed response from another chain id, the ChainLock staleness floor at and past the bound, the height watermark refusing an older state after an SDK rebuild, queries without endpoints, and input bounds.
  • tests/signing.rs pins every builder byte for byte against rs-dpp-generated vectors; tests/decoders.rs covers the stored-document decoders; unit tests pin the contested-state heuristic and normalization idempotence. 36 tests, cargo clippy --all-targets -D warnings, cargo fmt --check, cargo machete clean.
  • scripts/cxx-smoke.sh links and runs from C++ (macOS, debug and release).
  • Live testnet from a release-built C++ driver, as described above.
  • An independent code review pass and a simplification pass were applied before opening.

Breaking Changes

None to existing crates. packages/rs-sdk/README.md and packages/dash-platform-queries/README.md now point C++ embedders here.

Checklist:

  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have added or updated relevant unit/integration/functional/e2e tests
  • I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
  • I have made corresponding changes to the documentation if needed

For repository code-owners and collaborators only

  • I have assigned this pull request to a milestone

@coderabbitai

coderabbitai Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

A C++ application that wants Dash Platform with its own trust context and signing keys had no supported path: rs-sdk-ffi is a C ABI shaped for mobile wallets that fetch quorum keys from a trusted HTTP service and hold private keys in-process. Dash Core's platform GUI needs the opposite: quorum keys from its locally synced LLMQ store, endpoints from its deterministic masternode list, signatures from its wallet, and no key or trust ever leaving the node.

packages/rs-platform-cxx is a thin cxx bridge over dash-sdk. The embedder pushes endpoints, Platform quorum keys, its best ChainLock height and a digest-signing callback; the SDK owns query construction, transport (TLS to the evonodes), retries with address banning, proof verification and protocol-version tracking. Queries go through the SDK's Fetch/FetchMany so the rich query it built is what it verifies against; no wire request is ever reconstructed from bytes. On top of the SDK's signed-time window and monotonic Platform height, the client refuses a verified response whose Tenderdash chain id is not the network's or whose signed core-chain-locked height trails the embedder's ChainLock by more than 288 blocks. Every bridge entry point runs under catch_unwind, so a panic anywhere in the SDK surfaces as rust::Error rather than aborting the embedding process; the crate refuses to build under panic=abort.

Document assembly is dash-platform-queries' pure DPNS/DashPay builders; signing is dpp's Signer over the callback, with dash-sdk's structure validation before serialization. Broadcast rejections carry DAPI's consensus error decoded through the SDK's error conversion.

Tests replay drive-proof-verifier's proof-vector corpus through dash-sdk's mock transport (only the socket is mocked; the SDK runs the GroveDB replay and the BLS quorum check against the key pushed through the client) and cover unknown quorum key, wrong quorum type, tampered signature, foreign chain id, the ChainLock staleness floor, the height watermark surviving an SDK rebuild, cancellation and input bounds; builders are pinned byte for byte against rs-dpp-generated vectors; tests/cxx_smoke.cc links and runs from C++ in CI. Validated against live testnet from a release-built C++ driver: identity, nonce, DPNS resolve (registered and proven absent), names-of-identity, prefix search, profile, contact requests, contested vote state and a rejected broadcast all verify in 0.3 to 2 s; bit-flipped quorum keys fail at the BLS check.
@PastaPastaPasta
PastaPastaPasta force-pushed the feat/shared-dpns-dashpay-builders branch from 0631c07 to 5279114 Compare September 8, 2026 21:16
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this pull request Sep 8, 2026
…crate

dashpay/platform#4633 rebuilds the Platform CXX bindings as a thin bridge over dash-sdk: the SDK owns DAPI transport, retries and proof verification, and Core supplies endpoints, quorum keys, its ChainLock height and wallet signatures. The crate is an ordinary workspace member now, so the package vendors from the workspace root (the lockfile made vendorable by dashpay/platform#4631), builds with -p dash-platform-cxx, and installs the header tree the crate's build.rs stages plus the static archive; the nested standalone manifest and install.sh are gone with the old design.

mbedtls leaves depends: the SDK carries its own TLS stack (rustls with the system trust store), so Core no longer links a TLS library for Platform. The vendoring config gains the workspace's git sources.

Validated on aarch64-apple-darwin: make -C depends PLATFORM_GUI=1 platform_cxx vendors 840 crates (150 MB archive) and builds the crate offline in 3 minutes; the staged prefix carries include/dash/platform/{ffi.h,signer.h}, include/rust/cxx.h and lib/libdash_platform_cxx.a. The knob-off package set is unchanged.
PastaPastaPasta added a commit to PastaPastaPasta/dash that referenced this pull request Sep 8, 2026
…ble-platform-gui

The Qt-free client library dash-qt drives for DashPay: per-network parameters and system contract ids, the PlatformClient interface, DPP decoding and state-transition adapters, and the wallet record formats. Where the earlier revision (dashpay#7626) carried its own gRPC-Web/TLS transport, hand-written protobuf and CBOR encoders, per-endpoint retry and freshness tracking, and handed request/response byte pairs to a transport-free verifier, this one is a thin consumer of the Dash Platform SDK through dash-platform-cxx (dashpay/platform#4633). The SDK owns query construction, DAPI transport, retries with address banning, proof verification (GroveDB replay plus the Tenderdash quorum signature against the keys this node pushes from its LLMQ store), protocol-version tracking and the chain-id and ChainLock freshness checks; the node supplies evonode endpoints from its deterministic masternode list, the Platform quorum keys, its best ChainLock height and wallet signatures through a digest callback, so private keys never leave the wallet.

The PlatformClient interface the GUI programs against is unchanged apart from gaining an sdk() accessor; the production implementation keeps its single worker thread and callback marshalling and forwards each query to the SDK handle. Absence stays proven, never inferred: an empty result only reaches a callback after the SDK verified a proof of it. The DPP decoders and state-transition builders take the SDK handle so they build under the protocol version the SDK has seen the network run, ratcheted up from the per-network floor in params.cpp. The C++ transport, protobuf, CBOR, retry and freshness code and their unit tests are gone with the design; the DPP byte-exactness suite and the wallet key tests stay, and the fuzz harness keeps the decoder targets (proof verification is fuzzed upstream).

Validated on aarch64-apple-darwin against a depends prefix carrying the SDK-backed archive: configure detects the bindings, libdash_platform.a and test_dash build, platform_dpp_tests and platformkeys_tests pass.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant